// Copyright (c) Appeon. All rights reserved.
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. 
// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

namespace SnapObjects.Data
{
    /// <summary>
    ///     Represents an object that can unpack a data package which contains multiple types of elements. 
    ///     The data package must conform to the specified package format.
    /// </summary>
    public interface IDataUnpacker
    {
        /// <summary>
        ///     Gets the raw string of text which contains all of the elements in the IDataUnpacker object.
        /// </summary>
        string Raw { get; }

        /// <summary>
        ///     Gets the format of the text specified when creating the IDataUnpacker object.
        /// </summary>
        DataFormat DataFormat { get; }

        /// <summary>
        ///     Gets the number of elements added in the IDataUnpacker object.
        /// </summary>
        int Count { get; }

        /// <summary>
        ///     Gets the keys of all of the elements in the IDataUnpacker object.
        /// </summary>
        string[] Keys { get; }

        /// <summary>
        ///     Checks whether the specified key exists in the IDataUnpacker object.
        /// </summary>
        /// <param name="key">The key of the element to look for.</param>
        /// <returns>Returns true if the element exists; otherwise, false.</returns>
        bool ContainsKey(string key);


        /// <summary>
        ///     Removes the element from the IDataUnpacker object according to the specified key.
        /// </summary>
        /// <param name="key">The key of the element to remove.</param>
        /// <returns>Returns true if the element is successfully removed; returns false if the key was not found.</returns>
        bool RemoveKey(string key);

        /// <summary>
        ///     Gets the raw string of text for the specified element.
        /// </summary>
        /// <param name="key">The key specifying which element to get the raw string of text.</param>
        /// <returns>Returns the raw string of text for the element if the key exists; otherwise, returns String.Empty.</returns>
        string GetRaw(string key);
    }
}
